OpenEdge Development: <br />Web Services Preface

This manual describes how OpenEdge® supports Web services. It describes the technology for exposing AppServer™ application services as Web services (Progress® 4GL Web services), and how to access industry Web services from the Progress 4GL as a Web service client. It also describes the requirements for programming industry Web service clients to access Progress 4GL Web services. And it defines the Web services industry standards that OpenEdge supports.

This manual provides a brief overview of Web services architecture in OpenEdge. However, for a complete description of the Web services architecture in OpenEdge, including all components and how they work together, see OpenEdge Getting Started: Application and Integration Services .

This manual describes the general procedures and facilities for building Progress 4GL Web services, as well as specific client requirements. However, for specific information on Web service development, deployment, and administration, see the following documentation:

Audience

Organization

Provides a general overview of Web services in OpenEdge, describing how to develop, deploy, and manage Progress 4GL Web services, and how you can access industry Web services from a Progress 4GL application. This includes a brief overview of the Web Service Description Language (WSDL) and Simple Object Access Protocol (SOAP) that provides part of the foundation for Web services in OpenEdge. This chapter also describes the industry Web service standards that OpenEdge supports.

Describes how the interface to Progress 4GL Web services is based on the Open Client object model and defined in a Web Service Description (WSDL) file.

Describes how to program client access to Progress 4GL Web services using the Open Client object model, including a description of session model programming, data type mapping, handling SOAP headers, and SOAP faults.

Describes, in detail, the techniques for coding Progress 4GL Web service operations using VB.NET as the sample client platform, showing the types of SOAP messages that are generated for various types of SOAP requests supported by the Open Client object model.

Describes the sample Progress 4GL Web services that are installed with OpenEdge and the sample client applications to access them (also installed).

Describes how to test and debug Progress 4GL Web services using log files, SOAP viewers, and basic SOAP fault handling techniques.

Describes how to run the WSDL Analyzer to generate documentation on a Web service. This documentation describes how to connect to a Web service defined in the WSDL and how to call its operations from the 4GL. The chapter also describes how OpenEdge maps Progress 4GL data types to the XML Schema data types interpreted by Web services.

Describes how to connect to and manage connections to a Web service from the 4GL once you have generated the WSDL documentation for it.

Describes how to invoke and manage Web service operations from the 4GL once you have generated the WSDL documentation for it. This includes information on how to configure Web service operations for managing SOAP message headers in the 4GL.

Describes how to manage SOAP message headers in the 4GL for Web service operations that are configured for SOAP header management. This includes a detailed description of the 4GL techniques for accessing, manipulating, creating, and managing all elements of a SOAP message header.

Describes how to manage errors from 4GL requests to Web services in general and for SOAP faults in particular. This includes a detailed description of the 4GL techniques for accessing all elements of a SOAP fault message.

Describes some of the sample 4GL applications installed with OpenEdge that access Web services, both public Web services and sample Web services provided with OpenEdge for deployment.

Describes a sample scenario in which a .NET client application is developed to access a Progress 4GL Web service.

Describes a sample scenario in which a Java™ client application is developed to access a Progress 4GL Web service.

Provides a quick reference to the basic Progress 4GL elements provided by OpenEdge to access Web services.

Describes in finer detail the key rules used to transform data for Web service operation parameters between alternative mappings of Progress 4GL data types and XML Schema data types.

Describes the syntax for commands and utilities documented in this manual. If this manual provides the primary documentation for a command or utility, the syntax for that command or utility appears in this appendix.

Typographical conventions


Convention	Description
Bold	Bold typeface indicates commands or characters the user types, provides emphasis, or the names of user interface elements.
Italic	Italic typeface indicates the title of a document, or signifies new terms.
SMALL, BOLD CAPITAL LETTERS	Small, bold capital letters indicate OpenEdge® key functions and generic keyboard keys; for example, GET and CTRL.
KEY1+KEY2	A plus sign between key names indicates a simultaneous key sequence: you press and hold down the first key while pressing the second key. For example, CTRL+X.
KEY1 KEY2	A space between key names indicates a sequential key sequence: you press and release the first key, then press another key. For example, ESCAPE H.
Syntax:
`Fixed width`	A fixed-width font is used in syntax statements, code examples, system output, and filenames.
`Fixed-width italics`	Fixed-width italics indicate variables in syntax statements.
`Fixed-width bold`	Fixed-width bold indicates variables with special emphasis.
UPPERCASE fixed width	Uppercase words are Progress® 4GL language keywords. Although these are always shown in uppercase, you can type them in either uppercase or lowercase in a procedure.
	This icon (three arrows) introduces a multi-step procedure.
	This icon (one arrow) introduces a single-step procedure.
Period (.) or colon (:)	All statements except `DO`, `FOR`, `FUNCTION`, `PROCEDURE`, and `REPEAT` end with a period. `DO`, `FOR`, `FUNCTION`, `PROCEDURE`, and `REPEAT` statements can end with either a period or a colon.
[ ]	Large brackets indicate the items within them are optional.
[ ]	Small brackets are part of the Progress 4GL language.
{ }	Large braces indicate the items within them are required. They are used to simplify complex syntax diagrams.
{ }	Small braces are part of the Progress 4GL language. For example, a called external procedure must use braces when referencing arguments passed by a calling procedure.
\|	A vertical bar indicates a choice.
...	Ellipses indicate repetition: you can choose one or more of the preceding items.

Examples of syntax descriptions

In this example, ACCUM is a keyword, and aggregate and expression are variables:

Syntax
ACCUM `aggregate expression`

FOR is one of the statements that can end with either a period or a colon, as in this example:

FOR EACH Customer: DISPLAY Name. END.

In this example, STREAM stream, UNLESS-HIDDEN, and NO-ERROR are optional:

In this example, the outer (small) brackets are part of the language, and the inner (large) brackets denote an optional item:

A called external procedure must use braces when referencing compile-time arguments passed by a calling procedure, as shown in this example:

Syntax
DISPLAY [ STREAM `stream` ] [ UNLESS-HIDDEN ] [ NO-ERROR ]

Syntax
INITIAL [ `constant` [ , `constant` ] ]

Syntax
{ `&argument-name` }

In this example, EACH, FIRST, and LAST are optional, but you can choose only one of them:

In this example, you must include two expressions, and optionally you can include more. Multiple expressions are separated by commas:

Syntax
PRESELECT [ EACH \| FIRST \| LAST ] `record-phrase`

Syntax
MAXIMUM ( `expression` , `expression` [ , `expression` ] ... )

In this example, you must specify MESSAGE and at least one expression or SKIP [ (n) ], and any number of additional expression or SKIP [ ( n ) ] is allowed:

Syntax
MESSAGE { `expression` \| SKIP [ ( `n` ) ] } ...

In this example, you must specify {include-file, then optionally any number of argument or &argument-name = "argument-value", and then terminate with }:

Long syntax descriptions split across lines

Some syntax descriptions are too long to fit on one line. When syntax descriptions are split across multiple lines, groups of optional and groups of required items are kept together in the required order.

Complex syntax descriptions with both required and optional elements

Some syntax descriptions are too complex to distinguish required and optional elements by bracketing only the optional elements. For such syntax, the descriptions include both braces (for required elements) and brackets (for optional elements).

Syntax
{ `include-file` [ `argument` \| `&argument-name = "argument-value"` ] ... }

Syntax
WITH [ ACCUM `max-length` ] [ `expression` DOWN ] [ CENTERED ] [ `n` COLUMNS ] [ SIDE-LABELS ] [ STREAM-IO ]

In this example, ASSIGN requires either one or more field entries or one record. Options available with field or record are grouped with braces and brackets:

Syntax
ASSIGN { [ FRAME `frame` ] { `field` [ = `expression` ] } [ WHEN `expression` ] } ... \| { `record` [ EXCEPT `field` ... ] }

Example procedures

This manual provides numerous example procedures that illustrate syntax and concepts. You can access the example files and details for installing the examples from the following locations:

After you install the examples, you can find the Web services samples in the following location:

OpenEdge messages

OpenEdge displays several types of messages to inform you of routine and unusual occurrences:

http://www.progress.com/products/documentation

`Doc_and_Samples_Install`/src/samples/webservices/

OpenEdge messages end with a message number in parentheses. In this example, the message number is 200:

If you encounter an error that terminates OpenEdge, note the message number before restarting.

Obtaining more information about OpenEdge messages

In Windows platforms, use OpenEdge online help to obtain more information about OpenEdge messages. Many OpenEdge tools include the following Help menu options to provide information about messages:

** Unknown table name `table.` (200)

On UNIX platforms, use the Progress pro command to start a single-user mode character OpenEdge client session and view a brief description of a message by providing its number.

Start the Progress Procedure Editor:


`install-dir`/dlc/bin/pro

Press F3 to access the menu bar, then choose Help

Messages.

Type the message number and press ENTER. Details about that message number appear.

Press F4 to close the message, press F3 to access the Progress Procedure Editor menu, and choose File

Exit.

Preface

Purpose